home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / f90 / intro_libm.z / intro_libm
Encoding:
Text File  |  1998-10-30  |  12.5 KB  |  247 lines
  1. INTRO_LIBM(3M)                                         Last changed: 1-6-98
  2.  
  3.  
  4. NNAAMMEE
  5.      IINNTTRROO__LLIIBBMM - Introduction to math library routines
  6.  
  7. IIMMPPLLEEMMEENNTTAATTIIOONN
  8.      See individual man pages for implementation details
  9.  
  10. DDEESSCCRRIIPPTTIIOONN
  11.      The math routines are listed with the other intrinsic procedures in
  12.      alphabetical order, usually by generic function name.  Generic
  13.      function names are function calls that cause the compiler to compile
  14.      automatically the appropriate data type version of a routine, based on
  15.      the type of the input data.  For example, a call to the generic
  16.      function LLOOGG with a type of input data of complex compiles as CCLLOOGG.
  17.  
  18.      In general, on UNICOS systems, real functions have no prefix; integer
  19.      functions are prefixed with I, double precision functions are prefixed
  20.      with D, complex functions are prefixed with C, and double precision
  21.      complex functions are prefixed with CD (for example, AABBSS, IIAABBSS, DDAABBSS,
  22.      CCAABBSS, and CCDDAABBSS).  Functions with a type different from their
  23.      arguments are noted.  Real functions are usually the same as the
  24.      generic function name.
  25.  
  26.      On UNICOS/mk systems, two precisions are provided for real data:
  27.      32-bit or half precision real and 64-bit or single precision real.
  28.      The specific names for single precision real data provide a link to
  29.      the 64-bit intrinsic functions.  To ensure a link to the 32-bit
  30.      intrinsic functions, use the generic function names with 32-bit real
  31.      arguments.  For example, use LLOOGG for any of the types of real data.
  32.      Use AALLOOGG for single precision real arguments.  Extended precision
  33.      routines of math library routines are not provided on UNICOS/mk
  34.      systems and only some routines have vector versions.
  35.  
  36.      UNICOS/mk systems have an additional library named lliibbmmffaassttvv.  It
  37.      contains versions of selected math intrinsics which can be faster than
  38.      those in the default Math library.  These alternate versions are not
  39.      as accurate as the default library, and in some cases there are
  40.      argument restrictions, such as not allowing the use of the --OO option
  41.      on the compiler command line, or not allowing the use of infinities.
  42.      These alternate versions are generally faster for loops with 50 or
  43.      more iterations.  To use lliibbmmffaassttvv, use the --ll mmffaassttvv option on the
  44.      compiler's command line to load the library file.  You must compile
  45.      your code with the --OO33 or --OOvveeccttoorr33 option for the Fortran compiler or
  46.      use --hh vveeccttoorr33 with the C compiler.
  47.  
  48.      For information on inlining and vectorization of the Fortran 90
  49.      intrinsic procedures, see IINNTTRROO__IINNTTRRIINN(3I).
  50.  
  51.      The documentation for some of the most often used math library
  52.      routines also contains information on Cray Assembly Language (CAL)
  53.      register usage.
  54.  
  55.      For more information on calling library routines from various
  56.      programming languages, see the subsection on this man page titled
  57.      "Calling Functions from Fortran, C, or CAL."
  58.  
  59.      The math routines can be divided into the following general
  60.      categories:
  61.  
  62.      * General arithmetic functions - In the routine descriptions, complex
  63.        arguments are represented as
  64.  
  65.        _x = _x  + _i_x .
  66.             _r     _i
  67.        The real part of the complex number is _x ; _x  is the imaginary part.
  68.                                                _r   _i
  69.        Arguments and results are of the same type unless otherwise
  70.        indicated.
  71.  
  72.        Base values raised to a power and 64-bit integer division are called
  73.        implicitly from Fortran.
  74.  
  75.      * Exponential and logarithmic functions - The Cray Resesarch
  76.        exponential and logarithmic functions are similar to the ANSI
  77.        standard functions.  Each function has variations for real, double
  78.        precision, and complex values except the common logarithm function,
  79.        which addresses only real and double-precision values.  Complex
  80.        arguments are represented as
  81.  
  82.        _x = _x  + _i_x .
  83.             _r     _i
  84.        _x  is the real part of the complex number; _x  is the imaginary part.
  85.         _r                                          _i
  86.      * Trigonometric functions - The trigonometric functions are based on
  87.        the ANSI standard for Fortran, except for the cotangent function and
  88.        the CCOOSSSS (cosine and sine) function, which are Cray Research
  89.        extensions.
  90.  
  91.      * Type conversion functions - Type conversion functions change the
  92.        type of an argument.  In the routine description, complex arguments
  93.        are represented as
  94.  
  95.        _x = _x  + _i_x .
  96.             _r     _i
  97.        _x  is the real part of the complex number; _x  is the imaginary part.
  98.         _r                                          _i
  99.        Arguments and results are of the same type, unless indicated
  100.        otherwise.
  101.  
  102.      * Special functions - The special functions provide Fortran access to
  103.        a number of Standard C functions on UNICOS/mk and UNICOS systems.
  104.  
  105.      * Extended-precision routines - The extended-precision routines
  106.        perform double- and triple-precision arithmetic on UNICOS systems.
  107.  
  108.      * Boolean functions - The Boolean functions perform logical operations
  109.        and bit manipulations.  On UNICOS systems, the scalar subprograms
  110.        are external versions of Fortran inline functions.  They are all
  111.        called by address; results are returned in register S1.  All Boolean
  112.        functions are extensions.  These functions cannot be passed as
  113.        arguments with CF90 on any system.
  114.  
  115.    CCaalllliinngg FFuunnccttiioonnss ffrroomm FFoorrttrraann,, CC,, oorr CCAALL
  116.      Because of differences in the calling sequences for these languages,
  117.      and other language differences, important variations must be noted in
  118.      what functions can be called and how they are called.
  119.  
  120.      CCaalllliinngg ffrroomm FFoorrttrraann pprrooggrraammss
  121.      Some function names are in uppercase, and some are in lowercase.  The
  122.      Fortran language is case-insensitive; the Cray Research Fortran
  123.      compilers map all code in uppercase.  This means that functions with
  124.      lowercase names cannot be called from Fortran programs.
  125.  
  126.      CCaalllliinngg ffrroomm CC pprrooggrraammss
  127.      The C language is case-sensitive.  You must use the exact case
  128.      specified in the documentation when coding references to a function.
  129.  
  130.      All functions documented in this manual are callable from C programs.
  131.      The following rules can be used:
  132.  
  133.      * Because the function is not declared in a Standard C header,
  134.        explicitly declare the function as external, and specify the type of
  135.        the return value.
  136.  
  137.      * When calling the function, pass the address of the arguments by
  138.        using the address operator (&) for each argument or by using a
  139.        pointer to the argument.  Array names are considered to be
  140.        addresses; the address operator is not needed when using them.
  141.  
  142.      * The value returned by the function is the value, rather than the
  143.        address of the value.
  144.  
  145.      * Specify the ffoorrttrraann keyword.  The ffoorrttrraann keyword is an extension to
  146.        the C language and is useful when a C program calls a function
  147.        following the Cray Fortran calling sequence.  Specifying the ffoorrttrraann
  148.        keyword causes the C compiler to verify that the arguments used in
  149.        each call to the function are pass-by-address.
  150.  
  151.      CCaalllliinngg ffrroomm CCrraayy AAsssseemmbbllyy LLaanngguuaaggee ((CCAALL))
  152.      External references from Cray Assembly Language (CAL) are case-
  153.      sensitive, so you must use the exact name for functions as specified
  154.      on the man pages.  Two standard calling methods are supported by Cray
  155.      for math functions:  call-by-register and call-by-address.  For more
  156.      information on the details of calling sequences, see the documentation
  157.      for the CCAALLLL macro in _U_N_I_C_O_S _M_a_c_r_o_s _a_n_d _O_p_d_e_f_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l,
  158.      publication SR-2403.
  159.  
  160.      It is strongly recommended that function linkage be done using the
  161.      CCAALLLL macros.  Direct user calls to functions by using the return-jump
  162.      instruction should be avoided.
  163.  
  164.      Scalar functions return the result in registers S1 (and S2 if needed);
  165.      results for complex double precision are returned in S1 through S4.
  166.      Vector functions return their result in registers V1 (and V2 if
  167.      needed); complex double precision are returned in V1 through V4.  The
  168.      number of elements computed for vector functions is determined by the
  169.      contents of the vector-length register (VL) upon entry.
  170.  
  171.      For example, to call the SSQQRRTT routine using the call-by-address
  172.      sequence, let _a_r_g_1 be the address of the argument.
  173.  
  174.      CAL usage:
  175.  
  176.      EEXXTT     SSQQRRTT          Declare the name to be an external
  177.      CCAALLLL    SSQQRRTT,,((_a_r_g_1)   Call the function
  178.      (result)S1            The result is returned in register S1 and
  179.                            stored at the address result
  180.  
  181.      Note that the name SSQQRRTT must be uppercase.
  182.  
  183.      To call the SSQQRRTT routine by using the call-by-register convention:
  184.  
  185.      (S1) Value of the argument
  186.  
  187.      CAL usage:
  188.  
  189.      EEXXTT     SSQQRRTT%%         Declare the name to be an external
  190.      CCAALLLLVV   SSQQRRTT%%         Call the function
  191.      (result)S1            The result is returned in register S1 and
  192.                            stored at the address result
  193.  
  194.      To call the routine for vector SSQQRRTT using the call-by-register
  195.      convention, let V1 be the value of the vector argument and VL be the
  196.      vector length (between 1 and 64 values will be returned).
  197.  
  198.      CAL usage:
  199.  
  200.      EEXXTT     %%SSQQRRTT%%        Declare the name to be an
  201.                            external
  202.      CCAALLLLVV   %%SSQQRRTT%%        Call the function
  203.  
  204.      The result is returned in register V1.  The vector-length register VL
  205.      is unchanged.
  206.  
  207.      NNaammiinngg ccoonnvveennttiioonnss
  208.      Most of the UNICOS math library functions adhere to the following
  209.      naming convention:
  210.  
  211.      NNAAMMEE        Entry for call-by-address
  212.  
  213.      NNAAMMEE%%       Entry for scalar call-by-register
  214.  
  215.      %%NNAAMMEE%%      Entry for vector call-by-register
  216.  
  217.      Note that assembly language does not support generic function names or
  218.      automatic data type conversion.  For example, there is no math library
  219.      LLOOGG function for the logarithm routine.  You must specify either AALLOOGG,
  220.      DDLLOOGG, or CCLLOOGG for real, double-precision, or complex logarithm
  221.      respectively, and the argument must be of the correct type (real,
  222.      double-precision, or complex).
  223.  
  224.      RReeggiisstteerr ccoonnvveennttiioonnss
  225.      The documentation for some of the widely used user-callable functions
  226.      contains the register usage convention for the function.  By default
  227.      all the Cray Fortran compilers use the call-by-register convention for
  228.      math library functions (it is the fastest calling sequence), and will
  229.      put the %% prefix or suffix on the function name where needed.  If a
  230.      math library function is declared EEXXTTEERRNNAALL or IINNTTRRIINNSSIICC, the compilers
  231.      will generate code for the call-by-address method.
  232.  
  233. SSEEEE AALLSSOO
  234.      IINNTTRROO__IINNTTRRIINN(3I)
  235.  
  236.      _C_r_a_y _S_t_a_n_d_a_r_d _C _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication SR-2074
  237.  
  238.      _C_F_9_0 _C_o_m_m_a_n_d_s _a_n_d _D_i_r_e_c_t_i_v_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication SR-3901
  239.  
  240.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _1, publication SR-3902
  241.  
  242.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _2, publication SR-3903
  243.  
  244.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _3, publication SR-3905
  245.  
  246.      _I_n_t_r_i_n_s_i_c _P_r_o_c_e_d_u_r_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication SR-2138, for the
  247.